OpenEdge Development:<br />Progress 4GL Handbook Buffer handle methods

There are many methods you can use to perform operations dynamically on a buffer handle, both for static and for dynamic buffers. These are all dynamic equivalents of static statements you’re already familiar with. The principal value of these methods is that they let you define selection criteria for data retrieval and other values needed by the methods at run time. In many cases, you can use these methods effectively with queries and buffers that are defined as static objects, where the table names are known at compile time. The example that follows the method descriptions shows how to extend the Customers and Orders windows to use these dynamic methods on the query and buffer for the Customer table. These are summary method descriptions to make you aware of what is possible in working with buffer handles. As always, consult the online help or OpenEdge Development: Progress 4GL Reference for complete descriptions.

BUFFER-FIELD method

The BUFFER-FIELD method takes an argument, which can be either the name of a field or its ordinal position within the buffer, and returns the handle of that field object. You can then use the BUFFER-FIELD handle in turn to access various attributes of the field that are defined below. Note that BUFFER-FIELD is considered a method, rather than an attribute, only because it takes an argument to identify which field object you want. Beyond identifying the field, this method doesn’t really do anything except return its handle.

BUFFER-COMPARE and BUFFER-COPY methods

These two methods on a target buffer handle take a source buffer handle (and other optional values) as an argument. BUFFER-COMPARE compares the field values in the two buffers and returns a report of their differences. BUFFER-COPY copies the field values in the source buffer to the target buffer.

BUFFER-CREATE, BUFFER-DELETE, and BUFFER-RELEASE methods

These methods perform the same function as the CREATE, DELETE, and RELEASE statements do.

BUFFER-VALIDATE method

This method verifies that a record in a buffer complies with mandatory field and unique index definitions. It corresponds to the VALIDATE statement.

Buffer FIND methods

There is a whole set of methods you can use to perform a FIND operation on a buffer dynamically. Some of these include:

FIND-BY-ROWID — Takes a record RowID as an argument and reads that record into the record buffer. This method can be useful after a separate operation has recorded the RowID of a record using some other criteria and you wish to re-retrieve that record.

FIND-CURRENT — Re-reads the current record from the database, replacing the contents of the record buffer. This method can be useful if you want to refresh the record in case it has been changed, for example by another user, since it was originally read.

FIND-FIRST — Takes a WHERE clause (including the initial WHERE keyword) as an argument and retrieves the first record from the buffer’s table that satisfies the WHERE clause into the buffer.

FIND-LAST — Takes a WHERE clause as an argument and retrieves the last record from the buffer’s table that satisfies the WHERE clause into the buffer.

FIND-UNIQUE — Takes a WHERE clause as an argument that identifies a single record, and retrieves the one record from the buffer’s table that satisfies the WHERE clause into the buffer. If more than one record satisfies the WHERE clause, then no record is retrieved and the AMBIGUOUS buffer attribute is set to true.

The FIND methods are a very useful and efficient way of identifying a single record without the overhead of preparing and opening a query with selection criteria that identify that one record, and then doing a GET-FIRST() to position the query cursor to that one record.

In addition to the RowID argument for FIND-BY-ROWID and the WHERE clause argument for the FIND-FIRST, FIND-LAST, and FIND-UNIQUE methods, all five of these methods take optional arguments that you can use to specify the lock mode (NO-LOCK, SHARE-LOCK, or EXCLUSIVE-LOCK) and wait mode (if it is NO-WAIT). The default lock mode is SHARE-LOCK. You will generally want to change this to specify either NO-LOCK or EXCLUSIVE-LOCK, depending on whether you need to prepare to allow it to be changed and protect the record against changes by other users.

hBuffer:FIND-UNIQUE(“WHERE CustNum = 125”, NO-LOCK).

This example changes the lock mode to EXCLUSIVE-LOCK and the wait mode to NO-WAIT: